Developing a bundle for AS7 or EAP6 in Domain Mode

Since RHQ 4.12 you can use provisioning to deploy applications to an AS7 or EAP6 server in domain mode and execute CLI scripts. This enhancement is possible thanks to the bundle content handover feature, which allows target resource plugin components to participate in the bundle deployment.

In the rest of the document, we assume that you are already a little bit familiar with Ant Bundles and Bundle content handover.

The use case

I want to deploy a WAR file to an EAP 6 server group, but before it gets deployed, I need a CLI script to be executed to configure a datasource. Besides, I want to be able to define the maximum number of connections the datasource pool can create before the bundle is deployed.

The bundle archive

The bundle zip file must contain:

the ANT Bundle Recipe (deploy.xml)
a templated EAP6 CLI script to configure a datasource (prepareDatasource.cli)
the application WAR file (website.war)

The recipe

The recipe will have the following form.

deploy.xml

<?xml version="1.0"?>

<project name="handover-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">

  <rhq:bundle name="example.com (EAP 6)" version="1.1"
              description="example.com corporate website hosted on EAP 6">

    <rhq:input-property
        name="jdbc.pool.connections.max"
        defaultValue="40"
        required="true"/>
    <rhq:input-property
        name="server.group"
        defaultValue="main-server-group-01"
        required="true"/>

    <rhq:deployment-unit name="example.com deployment unit" compliance="filesAndDirectories">
      <rhq:file name="prepareDatasource.cli" replace="true">
        <rhq:handover action="execute-script"/>
      </rhq:file>
      <rhq:archive name="website.war">
        <rhq:handover action="deployment">
          <rhq:handover-param name="serverGroup" value="${server.group}"/>
        </rhq:handover>
      </rhq:archive>
    </rhq:deployment-unit>

  </rhq:bundle>

  <target name="main"/>

</project>

Before deploying the bundle RHQ will ask you which value you want to set for the jdbc.pool.connections.max and server.group properties
jdbc.pool.connections.max will be used to replace the @@jdbc.pool.connections.max@@ token in prepareDatasource.cli (replace="true")
Then the content of prepareDatasource.cli will be handed over to the the Host Controller resource component, which knows how to execute a CLI script
Eventually, the content of website.war will also be handed over, and the plugin component will deploy it to all servers in the server group named after server.group (handover-param name="serverGroup")

serverGroup handover param must point to an EAP domain server group

Do not confuse the serverGroup handover param with RHQ's bundle destination resource group.

The handover param must point to an EAP domain server group. It is the group of managed servers where the application must be deployed.

The bundle destination resource group encompasses the host controller resources for the bundle deployment.

More information on handover actions in AS7 / EAP6 plugin

The list of handover actions and associated parameters are documented in the AS7 plugin descriptor file. The content of this help section is displayed on your RHQ server:

Browse to Administration / Configuration / Agent Plugins
Click on JBoss Application Server 7.x
Scroll down to Bundle Handover Support